Skip to content

[OAS] extract schemas as referenced components#249978

Closed
TinaHeiligers wants to merge 44 commits intoelastic:mainfrom
TinaHeiligers:kbn24462_componentize_oas
Closed

[OAS] extract schemas as referenced components#249978
TinaHeiligers wants to merge 44 commits intoelastic:mainfrom
TinaHeiligers:kbn24462_componentize_oas

Conversation

@TinaHeiligers
Copy link
Copy Markdown
Contributor

@TinaHeiligers TinaHeiligers commented Jan 22, 2026 •
edited
Loading

Summary

fix #244662

Implements OpenAPI Schema (OAS) componentization to extract inline schemas into reusable components with $ref references in merge_ess_oas.js and merge_serverless_oas.js.

The aim is to provide OAS docs that support tooling better for consuming teams generating clients from the OAS docs.

Change highlights

  • Existing component traversal - Processes pre-existing components (e.g., bedrock_config, jira_secrets) to extract nested schemas

  • HTTP method filtering - Explicit allowlist (get, post, put, patch, delete, head, options, trace)

  • Object/composition handling - Extracts both object types and composition types (oneOf/anyOf/allOf)

  • Structural field detection - Extracts all objects with meaningful structure, not just those with properties

  • Component naming - Name generation includes with parentComponentName context to prevent collisions in nested schemas.

  • Documentation - mostly in jsdocs

  • enables unit testing! - oas_docs now supports jest tests 🎉

  • Documentation was added for features that require explanation or tutorials (jsdocs)

  • Unit or functional tests were updated or added to match the most common scenarios

Risks

  • This PR changes the OAS yaml files, carrying a risk that the new format isn't fully supported.

Potential future work

  • Introduce a --dry-run mode for preview and an --overwrite flag to either persist the changes explicitly.
  • Add CI check to ensure MAX_RECURSION_DEPTH is not exceeded.
  • Support previewing domain-specific OAS docs with inline schemas extracted to components

jloleysens
jloleysens reviewed Jan 22, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@jloleysens jloleysens left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @TinaHeiligers nice work, I did first pass of review and left a few comments. Mainly wanted to call out:

  • Can we ensure we are also traversing into the existing schemas.components object
  • Can we restructure our test strategy to rather make assertions like expect(schema).toEqual({ ... }). This would be a lot easier to follow and ensure that the tests are doing
  • Can we revert the deletions of api_docs?

Comment thread oas_docs/lib/componentize.js Outdated
Comment thread oas_docs/lib/process_schema.js Outdated
Comment thread oas_docs/lib/README.md Outdated
Comment thread oas_docs/lib/component_name_generator.js Outdated
Comment thread oas_docs/lib/component_name_generator.js
Comment thread oas_docs/lib/componentize.js Outdated
Comment thread oas_docs/lib/componentize.js Outdated
Comment thread oas_docs/lib/componentize.js Outdated
Comment thread oas_docs/lib/process_schema.js
Comment thread oas_docs/lib/process_schema.test.js
jloleysens
jloleysens reviewed Jan 23, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@jloleysens jloleysens left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for addressing my feedback @TinaHeiligers ! Left a couple further comments

Comment thread oas_docs/lib/componentize.js Outdated
Comment thread oas_docs/lib/process_schema.js
TinaHeiligers
TinaHeiligers commented Jan 24, 2026
View reviewed changes
Comment thread oas_docs/lib/componentize.test.js
TinaHeiligers
TinaHeiligers commented Jan 24, 2026
View reviewed changes
Comment thread oas_docs/lib/componentize.test.js Outdated
TinaHeiligers
TinaHeiligers commented Jan 24, 2026
View reviewed changes
Comment thread oas_docs/lib/componentize.test.js Outdated
TinaHeiligers
TinaHeiligers commented Jan 24, 2026
View reviewed changes
Comment thread oas_docs/lib/componentize.test.js
jloleysens
jloleysens reviewed Jan 26, 2026
View reviewed changes
Comment thread oas_docs/lib/componentize.js Outdated
@jloleysens
Copy link
Copy Markdown
Contributor

jloleysens commented Jan 27, 2026

/ci

@TinaHeiligers TinaHeiligers requested review from a team as code owners February 2, 2026 20:42
@botelastic botelastic Bot added the Team:Fleet Team label for Observability Data Collection Fleet team label Feb 2, 2026
@elasticmachine
Copy link
Copy Markdown
Contributor

elasticmachine commented Feb 2, 2026

Pinging @elastic/fleet (Team:Fleet)

@TinaHeiligers TinaHeiligers marked this pull request as draft February 3, 2026 02:27
@elasticmachine
Copy link
Copy Markdown
Contributor

elasticmachine commented Feb 3, 2026 •
edited
Loading

🤖 Jobs for this PR can be triggered through checkboxes. 🚧

ℹ️ To trigger the CI, please tick the checkbox below 👇

  • Click to trigger kibana-pull-request for this PR!
  • Click to trigger kibana-deploy-project-from-pr for this PR!
  • Click to trigger kibana-deploy-cloud-from-pr for this PR!
  • Click to trigger kibana-entity-store-performance-from-pr for this PR!
  • Click to trigger kibana-storybooks-from-pr for this PR!

TinaHeiligers
TinaHeiligers commented Feb 5, 2026
View reviewed changes
Comment thread oas_docs/lib/resolve_external_refs.js
});
}

async function resolveExternalReferences(
Copy link
Copy Markdown
Contributor Author

@TinaHeiligers TinaHeiligers Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

needed to resolve external references because `redocly doesn't seem to handle it

@elasticmachine

This comment was marked as outdated.

Sign in to view
flash1293
flash1293 requested changes Mar 6, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@flash1293 flash1293 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The streams change is kinda unrelated to the PR. Also, we shouldn't do this here, since this is about the streamlang syntax which isn't i18n-ified. Please either roll back or use {'includes'} / {'excludes'} to get rid of the warning

@TinaHeiligers
Copy link
Copy Markdown
Contributor Author

TinaHeiligers commented Mar 12, 2026 •
edited
Loading

@flash1293 I have no idea how that change got there! I'll be cleaning it up when the work resumes soon.

@TinaHeiligers TinaHeiligers mentioned this pull request Mar 22, 2026
Merged
6 tasks
@TinaHeiligers
Copy link
Copy Markdown
Contributor Author

TinaHeiligers commented Mar 22, 2026

closing as superseded by #258986

@TinaHeiligers TinaHeiligers mentioned this pull request Mar 24, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tobio tobio tobio left review comments

@flash1293 flash1293 flash1293 requested changes

@mdbirnstiehl mdbirnstiehl mdbirnstiehl approved these changes

@jloleysens jloleysens Awaiting requested review from jloleysens

Assignees

No one assigned

Labels

backport:skip This PR does not require backporting blocked Feature:OAS Work or issues related to Core-provided mechanisms for generating OAS release_note:skip Skip the PR/issue when compiling release notes Team:Core Platform Core services: plugins, logging, config, saved objects, http, ES client, i18n, etc t// Team:Fleet Team label for Observability Data Collection Fleet team

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[OAS] Automatically refactor request/response bodies to #/components/schemas

7 participants

@TinaHeiligers @jloleysens @elasticmachine @tobio @flash1293 @mdbirnstiehl @kibanamachine